                     Digital Distortion Area Choosers
                              Version 1.05
                        Release date: 2013-05-10

                                  by

                             Eric Oulashin
                     Sysop of Digital Distortion BBS
                 BBS internet address: digdist.bbsindex.com
                     Email: eric.oulashin@gmail.com



This file describes the Digital Distortion area chooser scripts.

Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup
4. Configuration file
5. DDMsgAreaChooser class: Properties & methods
6. DDFileAreaChooser class: Properties & methods
7. Revision History


1. Disclaimer
=============
The only guarantee that I can make about these scripts is that they will take
up space on your computer.  I have tested these with the Windows verison of
Synchronet 3.15 and 3.16 in Windows 2000 and Windows XP.
I created these scripts to customize the message & file area selection on my
BBS and am providing them to the Synchronet BBS community in case other
Synchronet sysops might find them useful.


2. Introduction
===============
The Digital Distortion message & file area chooser scripts provide a lightbar
or traditional user interface to let the user choose their message and file
area.  Also, the colors are customizable.  Additionally, the message area
chooser will show the date & time of the latest post for each of the
sub-boards.

The file & message area chooser scripts can be run in several ways:
- Executed from a JavaScript/Baja script
- Loaded in a JavaScript script, then use the DDMsgAreaChooser or
  DDFileAreaChooser object to let the user choose their message/file area
- Set up as a door

These scripts require Synchronet version 3.14 or higher.


3. Installation & Setup
=======================
Step 1: Copy the following files to a directory of your choice (i.e., sbbs/exec
or sbbs/mods):
DDFileAreaChooser.js
DDMsgAreaChooser.js
DDMsgAreaChooser.cfg
DDFileAreaChooser.cfg

Step 2: Set up the scripts to run on your BBS.
For these examples, I will use DDMsgAreaChooser.js.
If you want to use these scripts in you rcommand shell, their usage will
depend on whether your command shell is written in JavaScript or Baja.
To use these scripts in a JavaScript script, they can be used in one of
two ways:
1: Direct execution -
Where you want to have your area chooser functionality, simply insert this
line into your script:
load("DDMsgAreaChooser.js", true);
2: Use of the class -
The area chooser functionality is encapsulated into JavaScript objects so
that you can customize the settings & colors within your script if you like.
To do this, follow these steps:
 1. Include the following line in your JavaScript script (preferably near the
    top):
 load("DDMsgAreaChooser.js", false);
 2. Where you want to have area choosing functionality, instantiate the object
    and call its SelectMsgArea() function (for the message area chooser) or its
    SelectFileArea() function (for the file area chooser).  An example:
    var msgAreaChooser = new DDMsgAreaChooser();
	 msgAreaChooser.SelectMsgArea();

To run the message area chooser script from a Baja script, include the following:
   exec "?DDMsgAreaChooser.js"
Running the file area chooser script would be similar:
   exec "?DDFileAreaChooser.js"

If you would like to set up these scripts as doors, the following is an example
setup of the message area chooser (assuming it is placed in sbbs/exec or
sbbs/mods):
+[][?]----------------------------------------------------+
                   Message Area Chooser                   
----------------------------------------------------------
 Name                       Message Area Chooser         
 Internal Code              MSGARCHO                     
 Start-up Directory                                      
 Command Line               ?DDMsgAreaChooser.js         
 Clean-up Command Line                                   
 Execution Cost             None                         
 Access Requirements                                     
 Execution Requirements                                  
 Multiple Concurrent Users  Yes                          
 Intercept Standard I/O     No                           
 Native (32-bit) Executable No                           
 Use Shell to Execute       No                           
 Modify User Data           No                           
 Execute on Event           No                           
 Pause After Execution      No                           
 BBS Drop File Type         None                         
 Place Drop File In         Node Directory               
+----------------------------------------------------------+
To run that from a JavaScript, include this line:
bbs.exec_xtrn("MSGARCHO");
To run that from a Baja script, include this line:
exec_xtrn MSGARCHO


4. Configuration file
=====================
If you want to change the default beavior and colors for one of these scripts,
you can edit its configuration file, which is a plain text file.  The
configuration files have two sections: A behavior section (denoted by
[BEHAVIOR]) and a colors section (denoted by [COLORS]).  For each setting or
color, the syntax is as folows:

setting=value

where "setting" is the behavior setting or color, and "value" is the corresponding
value for the setting/color.  The colors are Synchronet color codes.

Also, comments are allowed in the configuration file.  Comments begin with a
semicolon (;).

Behavior section: Message area chooser
--------------------------------------
Setting                               Description
-------                               -----------
useLightbarInterface                  true/false: Whether or not to use a
                                      lightbar user interface.

showImportDates                       true/false: Whether or not to show the
                                      import dates (rather than message dates)
                                      in the latest date & time column in the
                                      sub-board lists.

Colors section: Message area chooser
------------------------------------
Color setting                        Description
-------------                        -----------
areaNum                              The color to use for area numbers

desc                                 The color to use for descriptions

numItems                             The color to use for the item counts

header                               The color to use for list headers

areaMark                             The color to use for the marker character
                                     used to show the area that is currently
                                     selected

latestDate                           The color to use for the latest post date

latestTime                           The color to use for the latest post time

bkgHighlight                         The background highlight color for
                                     lightbar mode

areaNumHighlight                     The color to use for an area number for
                                     a selected item in lightbar mode

descHighlight                        The color to use for a description for
                                     a selected item in lightbar mode

dateHighlight                        The color to use for the date for a
                                     selected item in lightbar mode

timeHighlight                        The color to use for the time for a
                                     selected item in lightbar mode

numItemsHighlight                    The color to use for the number of items
                                     for a selected item in lightbar mode

Behavior section: File area chooser
-----------------------------------
Setting                               Description
-------                               -----------
useLightbarInterface                  true/false: Whether or not to use a
                                      lightbar user interface.

Colors section: File area chooser
------------------------------------
Color setting                        Description
-------------                        -----------
areaNum                              The color to use for area numbers

desc                                 The color to use for descriptions

numItems                             The color to use for the item counts

header                               The color to use for list headers

areaMark                             The color to use for the marker character
                                     used to show the area that is currently
                                     selected

bkgHighlight                         The background highlight color for
                                     lightbar mode

areaNumHighlight                     The color to use for an area number for
                                     a selected item in lightbar mode

descHighlight                        The color to use for a description for
                                     a selected item in lightbar mode

numItemsHighlight                    The color to use for the number of items
                                     for a selected item in lightbar mode



5. DDMsgAreaChooser class: Properties & methods
===============================================
The following are the properties and methods of the DDMsgAreaChooser class, which
is the class used for letting the user choose a message area:
Property name                         Description
-------------                         -----------
showImportDates                       Boolean: Whether or not to show the
                                      import dates (rather than message dates)
                                      in the latest date & time column in the
                                      sub-board lists.

useLightbarInterface                  Boolean: Whether or not to use a
                                      lightbar user interface.

Methods
-------
Method name                           Description
-----------                           -----------
DDMsgAreaChooser()                    Constructor

SelectMsgArea()                       Lets the user choose a message sub-board.
                                      If the useLightbarInterface property is
                                      true and the user's terminal supports
                                      ANSI, it will use the lightbar interface;
                                      otherwise, it will use traditional
                                      interface.

SelectMsgArea_Lightbar()              Lets the user choose a message sub-board,
                                      with a lightbar user interface.

SelectMsgArea_Traditional()           Lets the user choose a message sub-board,
                                      with a traditional user interface.

ListMsgGrps()                         Lists the message groups

ListSubBoardsInMsgGroup(pGrpIndex,    Lists the sub-boards in the user's
                        pMarkIndex,   currently-selected message group.
                        pSortType)    The parameters are all optional.  They
                                      specify the index of the message group,
                                      the index of the sub-board to mark with
                                      the "chosen" character, and a sort type,
                                      which can be "none" (default sorting),
                                      "dateAsc" for date ascending,
                                      "dateDesc" for date descending, or
                                      "description" for description.

6. DDFileAreaChooser class: Properties & methods
===============================================
The following are the properties and methods of the DDMsgAreaChooser class, which
is the class used for letting the user choose a message area:
Property name                         Description
-------------                         -----------
useLightbarInterface                  Boolean: Whether or not to use a
                                      lightbar user interface.

Methods
-------
Method name                           Description
-----------                           -----------
DDFileAreaChooser()                   Constructor

SelectFileArea()                      Lets the user choose a file directory.
                                      If the useLightbarInterface property is
                                      true and the user's terminal supports
                                      ANSI, it will use the lightbar interface;
                                      otherwise, it will use traditional
                                      interface.

SelectFileArea_Lightbar()             Lets the user choose a file directory,
                                      with a lightbar user interface.

SelectFileArea_Traditional()          Lets the user choose a file directory,
                                      with a traditional user interface.

ListFileLibs()                        Lists the file libraries

ListDirsInFileLib(pLibIndex,          Lists the directories in the user's
                  pMarkIndex)         currently-selected file library.
                                      The parameters are optional.  They
                                      specify the index of the file library
                                      and the index of the directory to mark
                                      with the "chosen" character.
7. Revision History
===================
Version  Date         Description
-------  ----         -----------
1.05     2013-05-10   Bug fix in the file area chooser: When listing
                      directories in a file group, it would sometimes
                      crash due to an incorrect array index used, and
                      the array was not set up.  Those have been fixed.
1.04     2013-05-04   Updated to properly format message sub-boards and
                      file directories with more than 9999 entries.  The
                      formatting is now dynamically adjusted depending
                      on the greatest number of entries in a sub-board
                      for a message group or file directory in a file
                      library (the descriptions will shrink as the
                      text length of the greatest number of entries
                      increases).
1.03     2012-11-30   Bug fix: After leaving the help screen from the
                      sub-board/directory list, the top line is now
                      correctly written with the page information as "Page
                      # of #".
1.02     2012-10-06   For the lightbar interface, the current page number is
                      now displayed at the top of the screen (along with the
                      total number of pages) and is updated when going to a
                      new page.
1.01     2011-04-22   Fixed the wording when choosing a message sub-board and
                      file library.
1.00     2010-03-13   First public release